//+------------------------------------------------------------------+
//|               ChartObjectSubChart.mqh MQL5 子图表对象头文件        |
//|                版权所有 2000-2025, MetaQuotes Ltd.              |
//|                        官方网址: https://www.mql5.com            |
//+------------------------------------------------------------------+
//| 包含 MQL5 图表“子图表（SubChart）”对象类，用于在主图表内嵌入独立的迷你图表 |
//+------------------------------------------------------------------+
#include "ChartObject.h"  // 引入图表对象基类 CChartObject（提供通用属性与生命周期管理）

//+------------------------------------------------------------------+
//| CChartObjectSubChart 类（子图表对象）                            |
//| 功能：MQL5 图表子图表工具，在主图表的指定位置嵌入独立迷你图表，支持显示不同交易品种/周期的行情 |
//| 继承关系：public CChartObject（基于基础图表对象类，扩展子图表特有属性）    |
//| 核心特性：                                                      |
//|  1. 固定屏幕位置：由基准角（Corner）和 X/Y 距离（Distance）确定，不随主图表缩放变化 |
//|  2. 自定义尺寸：支持手动设置子图表的宽度（X_Size）和高度（Y_Size）          |
//|  3. 独立行情配置：可设置子图表显示的交易品种（Symbol）、时间周期（Period）    |
//|  4. 坐标轴控制：支持显示/隐藏子图表的时间轴（DateScale）和价格轴（PriceScale）|
//|  5. 禁止坐标绑定：屏蔽父类的 Time/Price 坐标接口，子图表位置与主图表 K 线无关 |
//| 适用场景：                                                      |
//|  - 同时监控关联品种行情（如主图表显示 EURUSD，子图表显示 GBPUSD）          |
//|  - 对比不同周期走势（如主图表为 1H 周期，子图表为 4H 周期）                |
//|  - 嵌入指标专用图表（如子图表仅显示 MACD 指标，不显示主行情）              |
//+------------------------------------------------------------------+
class CChartObjectSubChart : public CChartObject
  {
public:
   /**
    * @brief 构造函数：初始化子图表对象
    * @details 调用父类 CChartObject 构造函数，初始化子图表的基础属性（未绑定主图表）
    */
                     CChartObjectSubChart(void);

   /**
    * @brief 析构函数：销毁子图表对象
    * @details 依赖父类析构逻辑，自动删除主图表上的子图表对象，释放资源
    */
                    ~CChartObjectSubChart(void);

   //--- 子图表位置与尺寸属性接口（固定屏幕位置，与主图表 K 线无关）
   /**
    * @brief 获取子图表相对于基准角的 X 方向距离（屏幕像素）
    * @return int - X 距离（像素，从基准角向右的距离，决定子图表的水平位置）
    */
   int               X_Distance(void) const;

   /**
    * @brief 设置子图表相对于基准角的 X 方向距离
    * @param X [in] 新 X 距离（像素，建议根据主图表尺寸设置，如 10 表示距离基准角右侧 10 像素）
    * @return bool - 操作结果：true 表示设置成功，false 表示失败（未绑定主图表）
    */
   bool              X_Distance(const int X) const;

   /**
    * @brief 获取子图表相对于基准角的 Y 方向距离（屏幕像素）
    * @return int - Y 距离（像素，从基准角向下的距离，决定子图表的垂直位置）
    */
   int               Y_Distance(void) const;

   /**
    * @brief 设置子图表相对于基准角的 Y 方向距离
    * @param Y [in] 新 Y 距离（像素，如 10 表示距离基准角下方 10 像素）
    * @return bool - 操作结果：true 表示设置成功，false 表示失败（未绑定主图表）
    */
   bool              Y_Distance(const int Y) const;

   /**
    * @brief 获取子图表的基准角（屏幕参考角，决定位置计算原点）
    * @return ENUM_BASE_CORNER - 基准角枚举值（如 CORNER_LEFT_UPPER 表示主图表左上角，CORNER_RIGHT_LOWER 表示主图表右下角）
    */
   ENUM_BASE_CORNER  Corner(void) const;

   /**
    * @brief 设置子图表的基准角
    * @param corner [in] 新基准角（需为 ENUM_BASE_CORNER 枚举值）
    * @return bool - 操作结果：true 表示设置成功，false 表示失败（未绑定主图表）
    * @note 基准角改变后，X/Y 距离的参考原点同步变化（如从左上角改为右上角，X 距离从“向右”变为“向左”）
    */
   bool              Corner(const ENUM_BASE_CORNER corner) const;

   /**
    * @brief 获取子图表的宽度（屏幕像素）
    * @return int - 宽度（像素，决定子图表的水平显示范围）
    */
   int               X_Size(void) const;

   /**
    * @brief 设置子图表的宽度
    * @param size [in] 新宽度（像素，建议 ≥200 像素，确保能清晰显示 K 线与指标）
    * @return bool - 操作结果：true 表示设置成功，false 表示失败（未绑定主图表）
    */
   bool              X_Size(const int size) const;

   /**
    * @brief 获取子图表的高度（屏幕像素）
    * @return int - 高度（像素，决定子图表的垂直显示范围）
    */
   int               Y_Size(void) const;

   /**
    * @brief 设置子图表的高度
    * @param size [in] 新高度（像素，建议 ≥150 像素，避免因高度不足导致行情显示不全）
    * @return bool - 操作结果：true 表示设置成功，false 表示失败（未绑定主图表）
    */
   bool              Y_Size(const int size) const;

   //--- 子图表行情配置属性接口（独立于主图表的交易品种与周期）
   /**
    * @brief 获取子图表当前显示的交易品种
    * @return string - 交易品种代码（如 "EURUSD"、"XAUUSD"，为空字符串表示未设置）
    */
   string            Symbol(void) const;

   /**
    * @brief 设置子图表显示的交易品种
    * @param symbol [in] 目标交易品种代码（需为 MQL5 平台支持的品种，如 "GBPUSD"）
    * @return bool - 操作结果：true 表示设置成功，false 表示失败（未绑定主图表或品种不存在）
    * @note 设置后子图表会自动加载该品种的行情数据，无需手动刷新
    */
   bool              Symbol(const string symbol) const;

   /**
    * @brief 获取子图表当前的时间周期
    * @return int - 时间周期（MQL5 预定义周期值，如 PERIOD_M1 表示 1 分钟，PERIOD_H1 表示 1 小时）
    */
   int               Period(void) const;

   /**
    * @brief 设置子图表的时间周期
    * @param period [in] 目标时间周期（需为 MQL5 预定义周期枚举值，如 PERIOD_D1 表示日线）
    * @return bool - 操作结果：true 表示设置成功，false 表示失败（未绑定主图表或周期无效）
    * @note 周期改变后子图表会自动切换为对应周期的 K 线显示
    */
   bool              Period(const int period) const;

   //--- 子图表显示配置属性接口（缩放与坐标轴）
   /**
    * @brief 获取子图表的缩放比例（控制 K 线显示密度）
    * @return int - 缩放比例（默认值为 -1，代表自动适配；值越大，K 线显示越密集，可显示更多历史数据）
    */
   int               Scale(void) const;

   /**
    * @brief 设置子图表的缩放比例
    * @param scale [in] 新缩放比例（建议范围 -1~10，-1 为自动适配，≥0 为手动缩放）
    * @return bool - 操作结果：true 表示设置成功，false 表示失败（未绑定主图表）
    */
   bool              Scale(const int scale) const;

   /**
    * @brief 获取子图表时间轴（X 轴）的显示状态
    * @return bool - 状态值：true=显示时间轴（底部显示时间刻度），false=隐藏时间轴
    */
   bool              DateScale(void) const;

   /**
    * @brief 设置子图表时间轴的显示状态
    * @param scale [in] 新状态（true=显示，false=隐藏）
    * @return bool - 操作结果：true 表示设置成功，false 表示失败（未绑定主图表）
    * @note 隐藏时间轴可节省显示空间，适用于仅关注价格走势的场景
    */
   bool              DateScale(const bool scale) const;

   /**
    * @brief 获取子图表价格轴（Y 轴）的显示状态
    * @return bool - 状态值：true=显示价格轴（右侧显示价格刻度），false=隐藏价格轴
    */
   bool              PriceScale(void) const;

   /**
    * @brief 设置子图表价格轴的显示状态
    * @param scale [in] 新状态（true=显示，false=隐藏）
    * @return bool - 操作结果：true 表示设置成功，false 表示失败（未绑定主图表）
    * @note 隐藏价格轴可使子图表更简洁，适用于仅对比走势形态的场景
    */
   bool              PriceScale(const bool scale) const;

   //--- 禁止绑定主图表 K 线坐标（重写父类方法，屏蔽 Time/Price 接口）
   /**
    * @brief 禁止获取主图表 K 线时间坐标（子图表位置与主图表 K 线无关，此方法仅返回父类默认值）
    * @param point [in] 无效参数（子图表无 K 线锚点）
    * @return datetime - 父类默认时间值（无实际意义）
    */
   datetime          Time(const int point) const { return(CChartObject::Time(point)); }

   /**
    * @brief 禁止设置主图表 K 线时间坐标（子图表位置由屏幕像素决定，此方法始终返回 false）
    * @param point [in] 无效参数
    * @param time [in] 无效参数
    * @return bool - 操作结果：始终返回 false
    */
   bool              Time(const int point,const datetime time) const { return(false); }

   /**
    * @brief 禁止获取主图表 K 线价格坐标（子图表价格与主图表无关，此方法仅返回父类默认值）
    * @param point [in] 无效参数
    * @return double - 父类默认价格值（无实际意义）
    */
   double            Price(const int point) const { return(CChartObject::Price(point)); }

   /**
    * @brief 禁止设置主图表 K 线价格坐标（子图表位置由屏幕像素决定，此方法始终返回 false）
    * @param point [in] 无效参数
    * @param price [in] 无效参数
    * @return bool - 操作结果：始终返回 false
    */
   bool              Price(const int point,const double price) const { return(false); }

   //--- 子图表创建接口
   /**
    * @brief 在指定主图表创建子图表对象（通过位置与尺寸参数定义）
    * @param chart_id [in] 主图表 ID（0 表示当前图表，可通过 ChartID() 获取）
    * @param name [in] 子图表对象唯一名称（主图表内不可重复）
    * @param window [in] 主图表子窗口编号（0=主窗口，≥1=指标子窗口，子图表将嵌入该窗口）
    * @param X [in] 相对于基准角的 X 距离（像素，基准角默认左上角 CORNER_LEFT_UPPER）
    * @param Y [in] 相对于基准角的 Y 距离（像素）
    * @param sizeX [in] 子图表宽度（像素，建议 ≥200）
    * @param sizeY [in] 子图表高度（像素，建议 ≥150）
    * @return bool - 操作结果：true 表示创建成功（对象创建+绑定+位置+尺寸设置完成），false 表示失败
    * @note 1. 创建后需通过 Symbol() 和 Period() 方法设置子图表显示的行情，否则显示空白；
    *       2. 子图表默认隐藏坐标轴，可通过 DateScale(true) 和 PriceScale(true) 显示；
    *       3. 子图表的交互能力有限（如无法在子图表上绘制趋势线），主要用于行情展示
    */
   bool              Create(long chart_id,const string name,const int window,const int X,const int Y,const int sizeX,const int sizeY);

   /**
    * @brief 获取子图表对象类型（MQL5 预定义类型）
    * @return int - 对象类型标识（返回 OBJ_CHART，代表子图表对象）
    */
   virtual int       Type(void) const { return(OBJ_CHART); }

   //--- 序列化接口（重写基类方法，扩展子图表所有特有属性的读写）
   /**
    * @brief 将子图表参数（位置、尺寸、行情配置、显示设置）保存到文件
    * @param file_handle [in] 文件句柄（需提前以 FILE_WRITE 模式打开）
    * @return bool - 操作结果：true 表示保存成功，false 表示失败（文件无效/未绑定主图表）
    * @note 保存内容：基类通用属性 + 位置参数（X_Distance/Y_Distance/Corner） + 尺寸参数（X_Size/Y_Size） + 行情参数（Symbol/Period） + 显示参数（Scale/DateScale/PriceScale）
    */
   virtual bool      Save(const int file_handle);

   /**
    * @brief 从文件加载子图表参数（位置、尺寸、行情配置、显示设置）
    * @param file_handle [in] 文件句柄（需提前以 FILE_READ 模式打开）
    * @return bool - 操作结果：true 表示加载成功，false 表示失败（文件无效/未绑定主图表）
    */
   virtual bool      Load(const int file_handle);
  };
//+------------------------------------------------------------------+